ftp

Type

keyword

Summary

Used as a URL type with such commands as put and get to designate a file or directory on an FTP server.

Syntax

ftp

Description

Use the ftp keyword to upload or download files to or from an Internet site.

The URL scheme "ftp" indicates information located on an FTP server. An ftp URL consists of the following parts:

1. The string "ftp://"
2. An optional user name and password, separated by a colon (:)

   and followed by \"@\"
3. The name of the server
4. An optional port number preceded by a colon (:)
5. The name and location of a file or directory, starting with a
   slash (/)

If you don't specify a port number, port 21 is used. (This is the standard port for FTP.)

note

Most public FTP servers do not require a user name and password. For such servers, you need not specify any user name or password. If you don't specify a user name or password, LiveCode adds the "anonymous" user name and a dummy password automatically, in accordance with the conventions for public FTP servers.

Important

If your user name or password contains any of the characters ":", "@", "/", ".", or "|", use the URLEncode function to safely encode the user name or password before putting them into the URL. The following example constructs a URL for a user whose password contains the "@" character:

    put \"jim\" into userName
    put \"jsmith@example.org\" into userPassword
    put \"ftp://\" & userName & \":\" & URLEncode(userPassword) \
      & \"@ftp.example.com/title.txt\" into fileURLToGet
    get URL fileURLToGet

Here are some examples of valid ftp URLs:

• ftp://ftp.example.org/directory/ -- list of files and folders in a directory
• ftp://ftp.example.org/directory/file.exe -- a file on the server
• ftp://user:password@ftp.example.org/myfile -- a file accessed by a password
• ftp://ftp.example.com:3992/somefile -- using a nonstandard FTP port

An ftp URL is a container, and you can use the expression URL ftpURL in any statement where any other container type is used. When you get the value of an ftp URL, LiveCode downloads the URL from the server. (If you have previously cached the URL with the load command, it fetches the URL from the cache.)

A URL that ends with a slash (/) designates a directory (rather than a file). An ftp URL to a directory evaluates to a listing of the directory's contents. To change the format of directory listings, use the libURLSetFTPListCommand command.

FTP uploads and downloads that are performed using the ftp keyword are always transferred in binary mode: no character translation is performed. If you need to translate characters--for example, if you are uploading a text file to a different operating system and want to translate line endings--you must do so before uploading the file, since the put command will not do it for you.

note

Downloading a URL by using it in an expression is a blocking operation: that is, the handler pauses until LiveCode is finished getting the URL. Since contacting a server may take some time due to network lag, URL operations may take long enough to be noticeable, so you may want to set the cursor to the watch or otherwise indicate a delay to the user.

The following example shows how to set a flag in a global variable to prevent multiple downloads. The variable "downloadInProgress" is set to true while a download is going on, and back to false when the download concludes. If the user clicks the button again while the download is still going on, the handler simply beeps:

    on mouseUp
        global downloadInProgress
        if downloadInProgress then
           beep
           exit mouseUp
        end if
        put true into downloadInProgress -- about to start
        put URL (field \"FTP URL to get\") into field \"Command Result\"
        put false into downloadInProgress -- finished
    end mouseUp

To send any FTP command to an FTP server, use the libURLftpCommand function.

For technical information about URLs and the ftp URL scheme, see RFC 1630.

Important

The ftp keyword is part of the Internet library on desktop platforms. To ensure that the keyword works in a desktop standalone application, you must include this custom library when you create your standalone. In the Inclusions pane of the Standalone Application Settings window, make sure the "Internet" script library is selected.

Cross-platform note

On iOS and Android, you can use the ftp keyword without the need for the Internet library. When specifying URLs for iOS and Android, you must use the appropriate form that conforms to RFC 1630.

Examples

put URL "ftp://ftp.example.com/public/" into filesList

get URL "ftp://john:passwd@ftp.example.net:2121/picture.jpg"

put URL "ftp://files.example.org/file.txt" into URL "file:myFile.txt"

put field "Upload" into URL "ftp://me:secret@ftp.example.net/file.txt"

Related

glossary: LiveCode custom library, flag, standalone application, upload, folder, command, main stack, blocking, text file, statement, message, cache, Standalone Application Settings, container, URL, server, keyword, application, handler, word, expression, download

keyword: URL, file, ftp, button, http

library: library, Internet library

message: startup, openBackground, preOpenStack, openStack, preOpenCard

command: libURLSetFTPListCommand, libURLSetFTPMode, get, post, put, load, group, delete URL, libURLftpUpload, libURLDownloadToFile

control structure: function

function: result, files, libURLErrorData, value

Compatibility and Support

Introduced

LiveCode 1.1

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile